// StateAccessor.java
package org.zjx.core.state;

import java.time.Instant;
import java.util.Collection;
import java.util.Optional;

/**
 * 状态访问器接口 - 提供对游戏状态的访问和快照功能
 *
 * 主要功能：
 * 1. 按类型获取状态组件(可选)
 * 2. 获取完整状态快照
 * 3. 强制获取必须存在的状态组件(不存在时抛出异常)
 */
public interface StateAccessor {
    /**
     * 获取状态组件(可选)
     *
     * @param <T> 状态组件类型，必须继承自StateComponent
     * @param type 要获取的组件类型Class对象
     * @return 包含组件的Optional对象，如果组件不存在则返回空Optional
     */
    <T extends StateComponent> Optional<T> getComponent(Class<T> type);

    /**
     * 获取所有状态组件（用于全局验证）
     */
     Collection<StateComponent> getAllComponents();

    /**
     * 检查组件是否存在
     */
    default <T extends StateComponent> boolean containsComponent(Class<T> type) {
        return getComponent(type).isPresent();
    }

    <T extends StateComponent> void registerComponent(Class<T> type, T component);

    <T extends StateComponent> void removeComponent(Class<T> type);

    /**
     * 获取状态组件(必须存在)
     *
     * @param <T> 状态组件类型，必须继承自StateComponent
     * @param type 要获取的组件类型Class对象
     * @return 组件实例
     * @throws IllegalStateException 当组件不存在时抛出
     */
    default <T extends StateComponent> T requireComponent(Class<T> type) {
        return getComponent(type).orElseThrow(() ->
                new IllegalStateException("Required component not found: " + type.getSimpleName()));
    }
}